×
☰ See All Chapters

Exception handling using Spring @ExceptionHandler Annotation

@ExceptionHandler annotation is used to handle the exception globally per controller class. @ExceptionHandler annotation works only for classed annotated with org.springframework.stereotype.Controller annotation. You can annotate any method by @ExceptionHandler annotation in a controller class and mark the method as an exception handling method. You can optionally specify the exceptions that the method should handle, if no exceptions specified then will default to any exceptions listed in the method argument list. When an exception of the specified type occurs, Spring uses the exception handler method to handle the exception.  Within the exception handler method, you can specify any exception handling code like returning an error code or redirecting to an error page, etc.

Exception handling method arguments and return types

Handler methods which are annotated with this annotation are allowed to have very flexible signatures. They may have parameters of the following types, in arbitrary order:

  • An exception argument: declared as a general Exception or as a more specific exception. This also serves as a mapping hint if the annotation itself does not narrow the exception types through its value(). You may refer to a top-level exception being propagated or to a nested cause within a wrapper exception. As of 5.3, any cause level is being exposed, whereas previously only an immediate cause was considered. 

  • Request and/or response objects (typically from the Servlet API): You may choose any specific request/response type, e.g. ServletRequest / HttpServletRequest. 

  • Session object: typically HttpSession: An argument of this type will enforce the presence of a corresponding session. As a consequence, such an argument will never be null. Note that session access may not be thread-safe, in particular in a Servlet environment: Consider switching the "synchronizeOnSession" flag to "true" if multiple requests are allowed to access a session concurrently. 

  • WebRequest or NativeWebRequest: Allows for generic request parameter access as well as request/session attribute access, without ties to the native Servlet API. 

  • Locale: Locale for the current request locale (determined by the most specific locale resolver available, i.e. the configured LocaleResolver in a Servlet environment). 

  • InputStream / Reader for access to the request's content: This will be the raw InputStream/Reader as exposed by the Servlet API. 

  • OutputStream / Writer for generating the response's content: This will be the raw OutputStream/Writer as exposed by the Servlet API. 

  • Model: Model as an alternative to returning a model map from the handler method. Note that the provided model is not pre-populated with regular model attributes and therefore always empty, as a convenience for preparing the model for an exception-specific view. 

The following return types are supported for handler methods:

  • A ModelAndView object (from Servlet MVC). 

  • A Model object, with the view name implicitly determined through a RequestToViewNameTranslator. 

  • A Map object for exposing a model, with the view name implicitly determined through a RequestToViewNameTranslator. 

  • A View object. 

  • A String value which is interpreted as view name. 

  • @ResponseBody annotated methods (Servlet-only) to set the response content. The return value will be converted to the response stream using message converters. 

  • An HttpEntity<?> or ResponseEntity<?> object (Servlet-only) to set response headers and content. The ResponseEntity body will be converted and written to the response stream using message converters. 

  • void if the method handles the response itself (by writing the response content directly, declaring an argument of type ServletResponse / HttpServletResponse for that purpose) or if the view name is supposed to be implicitly determined through a RequestToViewNameTranslator (not declaring a response argument in the handler method signature). 

Limitations of @ExceptionHander annotation

  1. The @ExceptionHandler annotation can be used only in controller class. Exceptions rise in other classes still need to be handled by any other ways. 

  2. Separate exception handler methods in every controller class are needed and this may result in code duplication.   

Example for @ExceptionHander annotation

pom.xml

<project xmlns="https://maven.apache.org/POM/4.0.0"

        xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"

        xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/maven-v4_0_0.xsd">

        <modelVersion>4.0.0</modelVersion>

        <groupId>com.java4coding</groupId>

        <artifactId>ExceptionHandler_WithSpringBoot</artifactId>

        <packaging>war</packaging>

        <version>0.0.1-SNAPSHOT</version>

        <name>ExceptionHandler_WithSpringBoot</name>

        <parent>

                <groupId>org.springframework.boot</groupId>

                <artifactId>spring-boot-starter-parent</artifactId>

                <version>1.5.6.RELEASE</version>

        </parent>

        <dependencies>

                <dependency>

                        <groupId>org.springframework.boot</groupId>

                        <artifactId>spring-boot-starter-web</artifactId>

                </dependency>

                <dependency>

                        <groupId>org.apache.tomcat.embed</groupId>

                        <artifactId>tomcat-embed-jasper</artifactId>

                        <scope>provided</scope>

                </dependency>

                <dependency>

                        <groupId>org.springframework.boot</groupId>

                        <artifactId>spring-boot-devtools</artifactId>

                        <optional>true</optional>

                </dependency>

        </dependencies>

        <properties>

                <java.version>1.8</java.version>

        </properties>

</project>

DemoController.java

package com.java4coding;

import java.io.IOException;

 

import org.springframework.web.bind.annotation.ExceptionHandler;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RequestMethod;

import org.springframework.web.bind.annotation.RestController;

 

@RestController

public class DemoController {

 

        @RequestMapping("/hello")

        public String sayHello() {

                return "Hello!";

        }

       

        @RequestMapping(value = "/demo/not-exist", method = RequestMethod.GET, headers = "Accept=*/*")

        public String oneFaultyMethod() {

                if (true) {

                        throw new NullPointerException("Demo error message");

                }

                return null;

        }

 

        @ExceptionHandler({ NullPointerException.class, ArrayIndexOutOfBoundsException.class, IOException.class })

        public String handleException(NullPointerException ex) {

                return "Exception caught using @ExceptionHandler from DemoController";

        }

}

SpringBootDemo.java

package com.java4coding;

 

import org.springframework.boot.SpringApplication;

import org.springframework.boot.autoconfigure.SpringBootApplication;

 

@SpringBootApplication

public class SpringBootDemo {

        public static void main(String[] args) {

                SpringApplication.run(SpringBootDemo.class, args);

        }

}

application.properties

# Applicationn context name

server.contextPath=/ExceptionHandler

Project Directory Structure

spring-exceptionhandler-annotation-0
 

Output

spring-exceptionhandler-annotation-1
 
spring-exceptionhandler-annotation-2
 
All Chapters
Author